/*      $Id: Canopy.java 824 2008-09-11 18:20:22Z phrakt $    */
/*
 * Copyright (c) 2007 Jean-Francois Brousseau <phrakt@gmail.com>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
 * THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package ca.terraquati.canopy;


import ca.terraquati.canopy.http.*;
import ca.terraquati.canopy.handlers.Handler;

/**
 * The <code>Canopy</code> class provides access to the Canopy server's core
 * functionality.  It cannot be instantiated.
 *
 *
 *
 * @author Jean-Fran&ccedil;ois Brousseau
 */
public final class Canopy
{
	public enum Phase {
		READ,
		ACCESS,
		RESPONSE,
	};

	/**
	 * Returns the server's Management Information Base object. 
	 */
	public native static ManagementInformationBase getMIB();

	/**
	 * Returns the process ID of the Canopy server.
	 *
	 * @return a positive integer representing the UNIX process ID
	 */
	public native static int getPid();

	/**
	 * Returns the absolute path of the file where Canopy saved its
	 * process ID.
	 *
	 * @return a UNIX process ID
	 */
	public native static String getPidFile();

	/**
	 * Returns the identification string used by the Canopy server.  This
	 * is the string that is used as the value for the HTTP <i>Server</i>
	 * header.
	 *
	 * @return the server's identification string
	 */
	public native static String getServerIdent();

	/**
	 *
	 */
	public native static String getVersion();


	/**
	 * Checks whether the Canopy server's runtime root directory was
	 * changed at startup.
	 *
	 * @return <code>true</code> if the server changed its root directory,
	 *         <code>false</code> otherwise
	 */
	public native static boolean isChrooted();

	/**
	 * Checks whether the Canopy server is running as a daemon.
	 *
	 * @return <code>true</code> if the server is a daemon,
	 *         <code>false</code> otherwise
	 */
	public native static boolean isDaemon();

	/**
	 * Log a text message <code>msg</code> of priority <code>priority</code>
	 * to the Canopy server's logging channel.
	 *
	 * @param priority	the message's priority level
	 * @param msg		the text message to log
	 */
	public native static void log(final int priority, final String msg);

	/**
	 * @param p the request cycle phase at which the handler should be
	 *          registered
	 * @param h an instance of the class used as the handler
	 */
	public native static void addHandler(final Phase p, final Handler h);

	/**
	 * @param p the request cycle phase at which the handler should be
	 *          removed
	 * @param h the handler to remove
	 */
	public native static void removeHandler(final Phase p, final Handler h);

	/**
	 * Tell the server to perform a restart.
	 */
	public native static void restart();

	/**
	 * Tell the server to perform a shutdown.
	 */
	public native static void shutdown();
};
